home *** CD-ROM | disk | FTP | other *** search
/ MacWorld: Complete Mac Interactive / Macworld Complete Mac Interactive CD)(1994).iso / The Best of BMUG / Utilities / Text and Speech / Alpha.5.76 / Help / electricAlias Help < prev    next >
Text File  |  1994-03-08  |  9KB  |  294 lines
  1. ######### electricAlias Help LAST UPDATE: 01/24/93 9:29:39 AM #########
  2.  
  3. This help file refers to version 1.7 of electricAlias.tcl
  4.  
  5. QUICK START
  6.  
  7.     'electricAlias' is a general-purpose Tcl package that provides a 
  8.     flexible way to automate entering repetitive text. This text can be as 
  9.     simple as the current date, or can be a template containing many entry 
  10.     points where additional data is added. In this case, 'electricAlias' 
  11.     inserts the boilerplate and provides a convenient way to jump between 
  12.     entry points. Using electricAlias is as simple as typing a key word and 
  13.     hitting the tab key. 
  14.  
  15.     The following instructions will get you up and running ASAP. You will have 
  16.     three new bindings: 1. <TAB> will be bound to 'electricAlias-insert' and 2. 
  17.     <control-j> will be bound to 'nextStop', which jumps you to the next entry 
  18.     point in the current aliased text. 3. <control-shift-j> is bound to 
  19.     'prevStop', which jumps you to the previous entry point. 
  20.  
  21.     To use, simply place this file place in a folder named 
  22.     $HOME:Tcl:ElectricAlias: and append:
  23.  
  24.         'source $HOME:Tcl:ElectricAlias:electricAlias.tcl' 
  25.  
  26.     to AlphaBits.tcl. Also create a folder named 
  27.     $HOME:Tcl:ElectricAlias:Aliases and make sure to place at least a file 
  28.     named 'Aliases' in it with your default aliases. If you wish to use the 
  29.     language extensions feature, place respective files 'Aliases.Tcl', 
  30.     'Aliases.C', etc.. there as well. 
  31.  
  32.     To invoke in the current session you may manually source/load
  33.     it yourself; otherwise, quit and relaunch Alpha.
  34.  
  35.     Now go read about TEMPLATES below and examine the aliases files
  36.     to understand how it all fits together.
  37.  
  38. GENERAL USAGE
  39.  
  40.     ElectricAlias is simple to use.  Normally it is bound to the
  41.     <TAB> character, so you just type away.  You define aliases
  42.     in the alias definitions files $HOME:Tcl:ElectricAlias:aliases:aliases*.
  43.  
  44. PROCEDURE SYNTAX
  45.  
  46.     electricAlias-insert
  47.  
  48.             Invokes alias template insertion.  Text is scanned from
  49.             the current cursor position to the beginning of the line.
  50.             If the non-whitespace text immediately adjacent has an
  51.             alias entry, then template insertion proceeds.
  52.  
  53.     electricAlias-idefine
  54.  
  55.             An interactive mode to define aliases.  Crude.
  56.  
  57.     electricAlias-def MODE NAME ?DEFINITION?
  58.  
  59.             Defines or displays an alias template.  If DEFINITION
  60.             is omitted and the alias exists, then the current
  61.             definition is returned per TCL 'return'.
  62.             
  63.             Aliases may have embedded variables, TCL commands, stops,
  64.             line-ends and deletes as described under TEMPLATES below.
  65.  
  66.             If MODE begins with a bullet (•), then the alias is only effective
  67.             when used as the first token on a line.
  68.  
  69.     electricAlias-undefine MODE NAME
  70.  
  71.             Undefines entry for alias MODE and NAME
  72.  
  73.     electricAlias-exists MODE NAME
  74.  
  75.             Returns 1 if alias NAME exists; otherwise 0.
  76.  
  77.     electricAlias-list ?MODE?
  78.  
  79.             Inserts a sorted list of current definitions.
  80.             Specifying a MODE will restrict the returned list to
  81.             that mode.
  82.  
  83.             List may be used in another TCL.  Uses getalias
  84.             proc.
  85.  
  86.     electricAlias-mode ?NAME?
  87.  
  88.             Sets the current alias mode.  This is used to determine
  89.             which alias to use in a given situation.  Leading bullet (•),
  90.             if any, is removed.  This forces use of the MODE field when
  91.             defining aliases that must occur as the first token of a line.
  92.             
  93.             If the NAME is missing, then the current mode is returned.
  94.  
  95.     electricAlias-names ?MODE?
  96.  
  97.             Returns a list of currently defined alias names.
  98.             Specifying a MODE will restrict the returned list to
  99.             that mode.
  100.  
  101.     electricAlias-off
  102.  
  103.             Turns electricAlias off
  104.  
  105.     electricAlias-on
  106.  
  107.             Turns electricAlias on
  108.  
  109.     electricAlias-iundefine
  110.  
  111.             An interactive mode to remove aliases.  Crude.
  112.  
  113.     electricAlias-removeall ?MODE?
  114.  
  115.             Removes all alias definitions and variables
  116.             Specifying a MODE will restrict the returned list to
  117.             that mode.
  118.  
  119.     electricAlias-var MODE NAME ?DEFINITION?
  120.  
  121.             Defines an alias variable for use in templates.  If the pattern
  122.             §{NAME} is found during template insertion, it is replaced with
  123.             the DEFINITION.  This allows a single template to have multiple
  124.             uses.
  125.             
  126.             If the DEFINITION is omitted, then the current definition
  127.             is returned.
  128.  
  129.     electricAlias-version
  130.     
  131.             Returns the current version info.
  132.  
  133. TEMPLATE DEFINITIONS
  134.  
  135.     Templates provide a mechanism for inserting text with temporary stops.
  136.     Facility is also provided to preserve indentation and allow for alias
  137.     variable insertion and TCL commands.  This is accomplished with special
  138.     character sequences embedded within the template.  Hopefully, none of
  139.     these are needed in the inserted text itself.  Here are the definitions:
  140.  
  141.     \b        deletes one character to the left.  Useful for outdenting.
  142.  
  143.     •        inserts a temporary mark
  144.  
  145.     §«CMD»    inserts the results of executing the TCL command CMD.  Be
  146.             careful if your command contains anything that would be
  147.             construed as part of a regular expression.  To be safe use
  148.             only single procedures with simple arguments.  Also, the CMD
  149.             may not contain a closing '»'.
  150.  
  151.             It is possible for §«CMD»'s to be recursive (subject to the same
  152.             restrictions above) or include §{VAR}'s.
  153.  
  154.     §{VAR}    inserts an alias variable (IMPORTANT: inserted AFTER §«CMD»'s)
  155.  
  156.             It is possible for §{VAR}'s to be recursive or include §«CMD»'s
  157.             (subject to the §«CMD» restrictions above).
  158.  
  159.     \r        inserts a new-line break and cues procedure to preserve indentation
  160.             if alias mode is bullet type or when called explicitly.
  161.  
  162.     \n        identical to \r
  163.  
  164.     \t        inserts a tab for indentation
  165.  
  166.     Other escapes are as defined by TCL
  167.  
  168.     You can trick templates to insert some of the above with the following;
  169.     although, why you would want to is beyond me.
  170.     
  171.     '\ \bb' inserts literal '\b'
  172.     '§ \b«CMD»' inserts literal '§«CMD»'
  173.     '§ \b{VAR}' inserts literal '§{VAR}'
  174.  
  175. SIMPLE EXAMPLES
  176.  
  177.     The following examples show several templates that might be appropriate
  178.     for the C programming language:
  179.     
  180.     electricAlias-def •C while   "while (•) {\r\t•\r}/*endwhile*/•"
  181.     electricAlias-def •C for     "for (•;•;•) {\r\t•\r}/*endfor*/•"
  182.     electricAlias-def •C if      "if (•) {\r\t•\r}/*endif*/•"
  183.     electricAlias-def •C elseif  "\b} else if (•) {\r•"
  184.     electricAlias-def •C else    "\b} else {\r•"
  185.  
  186.     Suppose that the user has an open window for MYFILE.C (please bear
  187.     with the poor graphics):
  188.     +-------------------
  189.     | MYFILE.C
  190.     +-------------------
  191.     |
  192.     +-------------------
  193.  
  194.     By typing 'while\t' this would insert:
  195.     
  196.     +-------------------
  197.     | MYFILE.C
  198.     +-------------------
  199.     |while () {
  200.     |    
  201.     |}/*endwhile*/
  202.     +-------------------
  203.     
  204.     The cursor would be positioned inside the parentheses ready for an
  205.     expression to be typed.  When done with the expression, the user would
  206.     press CONTROL-J to jump to the next position where the body of the
  207.     WHILE loop would be entered.  A final CONTROL-J would position the user
  208.     just after the /*endwhile*/ comment.
  209.     
  210.     For this example, suppose the user types 'i < 5';
  211.  
  212.     Suppose the user type 'if\t' inside the body of the while, then we
  213.     would get:
  214.  
  215.     +-------------------
  216.     | MYFILE.C
  217.     +-------------------
  218.     |while (i < 5) {
  219.     |    if () {
  220.     |        
  221.     |    }/*endif*/
  222.     |}/*endwhile*/
  223.     +-------------------
  224.  
  225.     For the IF conditional suppose the user typed '*c != 0'.
  226.     Now in the body of the IF the user enters 'a = 1;else\ta = 2' and gets:
  227.     
  228.     +-------------------
  229.     | MYFILE.C
  230.     +-------------------
  231.     |while (i < 5) {
  232.     |    if (*c != 0) {
  233.     |        a = 1;
  234.     |    } else {
  235.     |        a = 2;
  236.     |    }/*endif*/
  237.     |}/*endwhile*/
  238.     +-------------------
  239.  
  240.     Suppose you don't like my indentation style for C.  Perhaps the following
  241.     definitions and the resulting code would be more suited to your tastes:
  242.  
  243.     electricAlias-def •C while   "while (•)\r  {\r\t•\r  }\r•"
  244.     electricAlias-def •C for     "for (•;•;•)\r  {\r    •\r  }\r•"
  245.     electricAlias-def •C if      "if (•)\r  {\r    •\r  }\r•"
  246.     electricAlias-def •C elseif  "\b\b}\r\b\b\b\belse if (•)\r\b\b{\r•"
  247.     electricAlias-def •C else    "\b\b}\r\b\b\b\belse\r\b\b{\r•"
  248.  
  249.     Now MYFILE.C would look like this:
  250.     
  251.     +-------------------
  252.     | MYFILE.C
  253.     +-------------------
  254.     |while (i < 5)
  255.     |  {
  256.     |    if (*c != 0)
  257.     |      {
  258.     |        a = 1;
  259.     |      }
  260.     |    else
  261.     |      {
  262.     |        a = 2;
  263.     |      }
  264.     |   
  265.     |  }
  266.     +-------------------
  267.  
  268.  
  269.  
  270. COPYRIGHT
  271.  
  272.     Copyright © 1993 by David C. Black
  273.     All rights reserved.
  274.  
  275.     Redistribution and use in source and binary forms are permitted
  276.     provided that the above copyright notice and this paragraph are
  277.     duplicated in all such forms and that any documentation,
  278.     advertising materials, and other materials related to such
  279.     distribution and use acknowledge that the software was developed
  280.     by David C. Black.
  281.  
  282.     THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
  283.     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  284.     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  285.  
  286. AUTHOR
  287.     
  288.     David C. Black
  289.     Internet: black@mpd.tandem.com
  290.     GEnie:    D.C.BLACK
  291.     USnail:   6217 John Chisum Lane, Austin, Tx 78749-1838
  292.  
  293. THE END
  294.